 /*******************************************************************************
  * Copyright (c) 2005, 2006 IBM Corporation and others.
  * All rights reserved. This program and the accompanying materials
  * are made available under the terms of the Eclipse Public License v1.0
  * which accompanies this distribution, and is available at
  * http://www.eclipse.org/legal/epl-v10.html
  *
  * Contributors:
  * IBM Corporation - initial API and implementation
  *******************************************************************************/

 package org.eclipse.ui.internal.provisional.cheatsheets;

 import java.util.Dictionary ;

 /**
  * A task within a composite cheat sheet.
  * <p>
  * This interface is not intended to be implemented by clients.
  * </p>
  */

 public interface ICompositeCheatSheetTask {
     /**
      * The constant that indicates that the task has not been
      * processed yet.
      */
     public static final int NOT_STARTED = 0;
     /**
      * The constant that indicates that the task is in progress.
      */
     public static final int IN_PROGRESS = 1;
     /**
      * The constant that indicates that the task has been skipped.
      */
     public static final int SKIPPED = 2;
     /**
      * The constant that indicates that the task has been completed.
      */
     public static final int COMPLETED = 3;
     /**
      * @return the unique identifier of this task.
      */
     public String getId();
     /**
      * @return the translatable name of the task.
      */
     public String getName();
     /**
      * Returns the kind of the task editor or task group.
      * @return task editor kind or <code>null</code> if no editor
      * is assoticated with this task.
      */
     public String getKind();
     /**
      * The task parameters are used to configure the
      * task editor with data meaningful to an editor of this kind.
      * @return the parameter names and values as specified in the
      * composite cheatsheet content file.
      */
     public Dictionary getParameters();
     /**
      * Returns the description of the task.
      * @return a plain String, or XML markup that can
      * be understood by FormText widget.
      * @see org.eclipse.ui.forms.widgets.FormText
      */
     public String getDescription();
     
     /**
      * Gets the text to be displayed when this task is completed
      * @return a plain String, or XML markup that can
      * be understood by FormText widget.
      * @see org.eclipse.ui.forms.widgets.FormText
      */
     public String getCompletionMessage();
     
     /**
      * Get the subtasks of this task. Each subtask may be
      * a task group or editable task. If the task is an editable task
      * there will be no children and an empty array will be returned.
      * @return an array of subtasks for this task
      */
     public ICompositeCheatSheetTask [] getSubtasks();
     
     /**
      * get the tasks which are required to be completed
      * before this task is started.
      * @return an array of tasks that must be completed
      * before this task can be started. The array will be
      * empty if this tasks is independent of other tasks.
      */
     public ICompositeCheatSheetTask [] getRequiredTasks();

     /**
      * Determine whether the required tasks for this task have
      * all been completed.
      * @return true if there are noi required tasks or all required
      * tasks have been completed.
      */
     public boolean requiredTasksCompleted();
     
     /**
      * Get the state of this task
      * @return NOT_STARTED, IN_PROGRESS, SKIPPED or COMPLETED.
      */
     public int getState();
     
     /**
      * Get the enclosing composite cheat sheet
      * @return the composite cheat sheet which contains this task
      */
     public ICompositeCheatSheet getCompositeCheatSheet();
     
     /**
      * Get the parent task group
      * @return The task group which contains this task or <code>null</code>
      * if this is the root of the composite cheat sheet.
      */
     public ITaskGroup getParent();

     /**
      * Test whether this task can be skipped. Skippable tasks are optional
      * tasks which are identified in the content file by having the attribute
      * <code>skip = "true"</code>. Only skippable tasks can be skipped.
      * @return true if this task has the skip attribute set to true in the
      * content file.
      */
     public boolean isSkippable();

 }

